Skip to content

Permit MCP Gateway documentation#613

Merged
orweis merged 6 commits intomasterfrom
cursor/permit-mcp-gateway-documentation-326e
Mar 16, 2026
Merged

Permit MCP Gateway documentation#613
orweis merged 6 commits intomasterfrom
cursor/permit-mcp-gateway-documentation-326e

Conversation

@orweis
Copy link
Contributor

@orweis orweis commented Mar 13, 2026 •
edited by cursor bot
Loading

Rewrites and restructures Permit MCP Gateway documentation to improve clarity, accelerate adoption for developers, and enhance credibility for security teams.

Changes

Landing Page (index.mdx) — Concise Intro + Navigation Hub

  • Outcome-driven hero with dual-audience framing (developers + security/IAM teams)
  • "Built on Permit.io" section explaining the control plane / data plane relationship
  • Trimmed to avoid content overlap with overview — delegates "what and why" detail to overview.mdx

Overview Page (overview.mdx) — Major Rewrite

  • New "How Permit and Permit MCP Gateway Are Connected" section
    • Permit as control plane and default data plane
    • Every Host = Permit Environment (1:1 mapping)
    • Two-dashboard model: app.permit.io + app.agent.security
  • Security and Trust Model section (what the gateway sees/enforces/logs, what it doesn't solve)
  • Comparison table vs API gateways, IAM platforms, manual access
  • Use Cases, When to Use, Deployment Options sections (moved from index.mdx)

Getting Started (guide.mdx) — Fast Activation Path

  • 5-minute Quick Start at the top (8 steps to first allowed call, denied call, and audit event)
  • Expected results after each setup step
  • Mini troubleshooting block for common quick-start issues

Architecture Page — Executive Summary + Control Plane

  • Executive summary before the deep technical dive
  • New "Permit.io as Control Plane and Data Plane" section with diagram
  • Control plane / data plane framing throughout

Permit.io Integration Page — Connection Explanation

  • New relationship overview table (Permit vs Gateway roles, dashboards, storage)
  • "Every gateway host maps to a Permit environment" explanation
  • Full policy engine capabilities available through the connection

Audit Logs — Investigation Examples

  • 5 practical investigation walkthroughs (denied action, human→agent tracing, server audit, access history, compliance report)

Host Setup — Rollout Guidance

  • 3-phase rollout plan: Pilot → Controlled Expansion → Production
  • Rollout principles (start restrictive, pilot before production, review before broadening)
  • Trust level keyword table replaced with example-based table + link to canonical reference

Advanced Features — Agent Interrogation + Claims Hygiene

  • New: Agent Interrogation — agentic-native identity mechanism using the MCP protocol itself
    • Composite identity: delegating human + workflow context + agent fingerprint
    • Value for policy: hard-gated tool access, per-workflow policy, drift-triggered reactions
    • Value for auditing: persistent identity, declared vs observed intent, full identity chain
    • Value for prompt injection protection: baseline fingerprinting, multi-dimensional drift detection
  • Linked Agent Verification and Intent-Based Access Control to Interrogation as underlying mechanism
  • Feature maturity summary table with honest status indicators
  • Maturity callouts for features under active development
  • Flagged marketing-site claims not yet supported in docs

CR Fixes

  • Subdomain example acme-pink-panda-6942 → acme-brave-coral-37 across all 9 files to match actual {prefix}-{adjective}-{color}-{2-digit} generation logic
  • Content overlap between index/overview/guide reduced — index trimmed to intro + navigation, overview owns the detailed pitch
  • Abbreviated trust level keyword lists in host-setup.mdx replaced with example-based table + link to canonical reference in guide.mdx

Naming Consistency — All Files

  • "Agent Security" → "Permit MCP Gateway" across all 12 documentation files
  • Config snippet names updated to permit-mcp-gateway
  • Zero remaining marketing metaphors or inflated claims

cursoragent and others added 3 commits March 13, 2026 15:53
@cursoragent @orweis
Rewrite landing, overview, and getting started pages for Permit MCP G…
2e29854 
…ateway

- Rewrite index.mdx as outcome-driven landing page with dual-audience framing
- Add 'When to Use', 'Who This Is For', deployment options, and use case sections
- Fix naming: 'Permit MCP Gateway' as primary name, not 'Agent Security'
- Rewrite overview.mdx with Security & Trust Model section
- Add comparison table vs existing tools (API gateways, IAM platforms)
- Add fast 5-minute activation path to Getting Started guide
- Add expected results after each setup step
- Add mini troubleshooting block for quick start

Co-authored-by: Or Weis <[email protected]>
@cursoragent @orweis
Fix naming consistency, improve architecture/audit/advanced pages
ebb96b6 
- Add executive summary to architecture page
- Add practical investigation examples to audit logs page
- Add rollout guidance section to host setup page
- Fix 'Agent Security' → 'Permit MCP Gateway' naming across all pages
- Rewrite advanced features with claims hygiene and maturity indicators
- Soften unverified claims (anomaly detection, shadow detection, sub-ms decisions)
- Add feature maturity summary table to advanced features

Co-authored-by: Or Weis <[email protected]>
@cursoragent @orweis
Final naming consistency: last Agent Security references and config s…
a82daeb 
…nippet names

Co-authored-by: Or Weis <[email protected]>
@cursor
Copy link

cursor bot commented Mar 13, 2026

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
Learn more about Cursor Agents

@netlify
Copy link

netlify bot commented Mar 13, 2026 •
edited
Loading

✅ Deploy Preview for permitio-docs ready!

Name Link
🔨 Latest commit 608a699
🔍 Latest deploy log https://app.netlify.com/projects/permitio-docs/deploys/69b8174597ff96000756de0c
😎 Deploy Preview https://deploy-preview-613--permitio-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

cursoragent and others added 2 commits March 14, 2026 16:41
@cursoragent @orweis
Add Permit ↔ Gateway connection information across docs
a06c627 
- Explain that Permit.io is the control plane and default data plane
- Clarify every Host maps 1:1 to a Permit Environment
- Document the full power of Permit policies available through the connection
- Explain the two-dashboard model: app.permit.io vs app.agent.security
- Add control plane / data plane diagram to architecture page
- Expand permit-integration page with relationship overview table
- Add 'Built on Permit.io' section to landing page
- Update deployment options with SaaS subdomain and PDP details

Co-authored-by: Or Weis <[email protected]>
@cursoragent @orweis
Add Agent Interrogation as advanced feature
e73b6f5 
- Describe agentic-native identity mechanism using the MCP protocol
- Explain composite identity: delegating human + workflow context + fingerprint
- Detail value for policy enforcement: hard-gated tool access, per-workflow
  policy, drift-triggered reactions, step-up consent
- Detail value for auditing: persistent identity, declared vs observed intent,
  full identity chain, drift history
- Detail value for prompt injection protection: baseline fingerprinting,
  multi-dimensional drift detection, session isolation
- Link existing Agent Verification and Intent-Based Access Control sections
  to Agent Interrogation as their underlying mechanism
- Update feature maturity summary table

Co-authored-by: Or Weis <[email protected]>
@EliMoshkovich
Copy link
Contributor

EliMoshkovich commented Mar 16, 2026

@orweis

  1. Subdomain example doesn't match generation logic (minor)
    The docs use acme-pink-panda-6942 as the example subdomain across all pages. The actual generation logic in platform/src/lib/host-naming.ts produces {prefix}-{adjective}-{color}-{2-digit-number} using the unique-names-generator library:

"panda" is not in either the adjectives or colors dictionary — it can never appear in a generated subdomain
"6942" is 4 digits — the code generates 2-digit numbers (10-99)
"pink" is a valid color but appears in the adjective position in the example
A realistic example would be acme-brave-coral-37. This appears in: index.mdx, overview.mdx, guide.mdx, host-setup.mdx, architecture.mdx, permit-integration.mdx, platform.mdx, consent-service.mdx, authentication-methods.mdx.

Impact: Cosmetic — users see their real subdomain in the dashboard. But it sets wrong expectations about the format.

  1. Content overlap between index, overview, and guide pages (suggestion, non-blocking)
    All three pages explain what the gateway does, the problem it solves, and the core concepts (trust levels, consent, audit). A reader going through the docs sequentially encounters the same "gateway is a proxy that adds auth/authz/consent/audit" pitch three times before reaching actionable setup steps. Consider trimming index.mdx to a brief intro + navigation links and letting overview.mdx own the "what and why".

  2. Trust level keyword lists abbreviated inconsistently (nitpick)
    guide.mdx has the complete keyword list for each trust level. host-setup.mdx uses abbreviated lists with "etc." (e.g., medium shows create, write, update, send, execute, deploy, etc. — omitting 14 of 20 keywords). Not wrong, but could link to the canonical list in the guide for consistency.

@cursoragent @orweis
Fix CR comments: subdomain example, content overlap, trust level lists
608a699 
- Replace acme-pink-panda-6942 with acme-brave-coral-37 across all 9 files
  to match actual generation logic ({prefix}-{adjective}-{color}-{2-digit})
- Also fix round-moccasin-19 and suffix-only references
- Trim index.mdx to concise intro + navigation hub; move Use Cases,
  When to Use, and Deployment Options into overview.mdx to eliminate
  triple repetition of the gateway pitch across index/overview/guide
- Replace abbreviated trust level keyword table in host-setup.mdx with
  example-based table and link to canonical reference in guide.mdx

Co-authored-by: Or Weis <[email protected]>
@orweis orweis marked this pull request as ready for review March 16, 2026 14:50
EliMoshkovich
EliMoshkovich approved these changes Mar 16, 2026
View reviewed changes
Copy link
Contributor

@EliMoshkovich EliMoshkovich left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — ready to merge

@orweis orweis merged commit e9fd37f into master Mar 16, 2026
4 checks passed
@orweis orweis deleted the cursor/permit-mcp-gateway-documentation-326e branch March 16, 2026 15:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@EliMoshkovich EliMoshkovich EliMoshkovich approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@orweis @EliMoshkovich @cursoragent